---
description: Компонент, который позволяет пользователю выбрать один или несколько вариантов из списка опций.
---

<Overview group="forms">

# Checkbox [tag:component]

Компонент, который позволяет пользователю выбрать один или несколько вариантов из списка опций.
Компонент представляет собой квадратный переключатель, который может быть в трёх состояниях: выбрано, не выбрано и не определено.

</Overview>

<Playground>
  ```jsx
  <Checkbox name="notifications">Уведомления включены</Checkbox>
  ```
</Playground>

## Применение компонента

- если вы используете компонент `Checkbox` для глобального управления состоянием другой группы компонентов `Checkbox`, используйте
  свойство `indeterminate` для индикации разного состояния дочерних переключателей;
- если вам необходим компонент, который предоставляет выбор более чем из двух взаимоисключающих значений,
  используйте группу компонентов [`Radio`](/components/radio).

## Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
React-компонентов, прочитать про это можно в [документации React](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable).

Для использования неконтролируемого режима достаточно просто _не_ передавать `checked` или передавать `defaultChecked`, если
требуется задать значение по умолчанию.
Для контролируемого режима используйте связку свойств `checked`/`onChange` для задания значения и его изменения.

Есть возможность также влиять на значение "не определено". В неконтролируемом режиме передавайте свойство `defaultIndeterminate`,
в контролируемом используйте свойство `indeterminate`. Получить значение "не определено" в `onChange` нельзя.

```jsx
// Неконтролируемое состояние, по умолчанию в состоянии "выбран"
<Checkbox defaultChecked />

// Неконтролируемое состояние, по умолчанию в состоянии "не определено"
<Checkbox defaultIndeterminate />

// Контролируемое состояние, значение "не выбран"
const [checked, setChecked] = React.useState(false);

<Checkbox checked={checked} onChange={(event) => setChecked(event.target.checked)} />;
```

## Состояния

### `disabled`

Свойство `disabled` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

<Playground>
  ```jsx
  <Checkbox name="notifications" disabled>
    Уведомления включены
  </Checkbox>
  ```
</Playground>

## Визуальное оформление

По умолчанию компонент использует для визуализации два набора (для `"regular"` и `"compact"` режима) стандартных иконок,
включающих три состояния. С помощью представленных ниже свойств вы можете определить собственные наборы иконок:

- `IconIndeterminate` - иконка для неопределенного состояния;
- `IconOffCompact` - иконка для не выбранного состояния в режиме `"compact"` (планшеты, десктоп);
- `IconOffRegular` - иконка для не выбранного состояния в режиме `"regular"` (мобильные устройства);
- `IconOnCompact` - иконка для выбранного состояния в режиме `"compact"` (планшеты, десктоп);
- `IconOnRegular` - иконка для выбранного состояния в режиме `"regular"` (мобильные устройства).

Рекомендуется использовать иконки размером `24px` для режима `"regular"` и `20px` для режима `"compact"`.

<Playground>
  ```jsx
  <Checkbox
    IconOffCompact={Icon20LikeOutline}
    IconOffRegular={Icon24LikeOutline}
    IconOnCompact={Icon20Like}
    IconOnRegular={Icon24Like}
  >
    Пицца с ананасами
  </Checkbox>
  ```
</Playground>

## Кастомизация

Компонент поддерживает свойство `slotProps`, которое даёт возможность прокинуть свойство в некоторые внутренние элементы.

Это удобно для добавления кастомных классов, data-атрибутов, aria-атрибутов, обработчиков событий, доступов к элементам через `getRootRef` и других расширений, не влияя на внешний API компонента.

<Playground>
  ```jsx
  const inputRef = React.useRef();

  return (
    <Checkbox
      defaultChecked={false}
      className="my-root-class"
      data-testid="checkbox-root"
      id="checkbox-input-id"
      slotProps={{
        root: {
          id: 'checkbox-root-id',
        },
        input: {
          className: 'my-input-class',
          'aria-label': 'checkbox',
          getRootRef: inputRef,
        },
      }}
    >
      Уведомления включены
    </Checkbox>
  )
  ```
</Playground>

## Доступность (a11y) [#a11y]

Компонент `Checkbox` обеспечивает базовую доступность, используя нативные `HTML`-элементы `input[type="checkbox"]` и `label`.

Для улучшения доступности рекомендуется предавать в компонент атрибуты `aria-labelledby`, `aria-label` и `aria-describedby`
для предоставления дополнительной информации об элементе.

## Свойства и методы [#api]

<PropsTable name="Checkbox">
### Checkbox [#checkbox-api]

### Checkbox.Input [#checkbox-input-api]

</PropsTable>
